vcMotionController

Motion controller is a behavior that is used to control motion of a mechanism through associated vcLinkJoints.

See in: Overview

Children -

Referenced by: vcControllerGroup.Controllers, vcJointDriver.OriginalController, vcSimJointDriverExportField.Controller, vcSingleDofLinkJoint.Controller

Properties

Learn how to use properties here. The properties are also inherited from the parent class.

Name	Type	Access	Description
DriverAccelerations	list[Real]	R	Gets or sets a list of internal driver accelerations.
DriverCount	Integer	R	Gets the number of internal drivers.
DriverPositions	list[Real]	RW	Gets or sets a list of internal driver positions.
DriverVelocities	list[Real]	R	Gets or sets a list of internal driver velocities.
Drivers	vcList[vcJointDriver]	R	Gets all internal drivers in their indexed order.
ExternalDriverCount	Integer	R	Gets the number of external drivers.
ExternalDriverPositions	list[tuple[Integer, Real]]	RW	Gets or sets a list of external driver positions. Each item is a tuple of (int driverIndex, double driverValue).
ExternalDrivers	vcList[vcJointDriver]	R	Gets a list of external drivers in the order they appear in their indexed list. Empty slots are skipped.
Groups	vcList[vcControllerGroup]	R	Gets all controller groups created on this controller.
IsStopped	Boolean	R	Gets the current stopped state.
Kinematics	vcKinematics	RW	Gets or sets the vcKinematics object to use with this controller.

Methods

Learn how to use methods here. The methods are also inherited from the parent class.

Name	Return Type	Parameters	Description
abort	None	None	Stops all movement (immediate) and clears the target / motion queue. Parameters: None Returns: None
addCoordinatedTarget	Integer	vcMotionControllerTarget target	Adds the given target to an internal queue. See more You can construct a target in Python with vcPtpTarget(), vcLinearTarget() or vcMultiDriverTarget(). Call moveCoordinated() after adding one or more targets to make sure motions are being processed. If target.TargetId is a positive integer, it is taken to mean an expected targetId value. This id value must not already be in use. If target.TargetId is zero, the next free id is automatically assigned to this target, and returned from this method call. Parameters: targetId (int): Identification number for the target. driverIndex (int): Index of the driver that this target applies to. isExternal (bool): False if this target applies to an internal driver, True if it applies to an external driver. valueType (vcDriverTargetValueType): Determines what the 'value' parameters means. value (float): The target value. Also see valueType. isSynchonized (bool): If True, this target will be marked to be synchronized with other targets for which this parameter is True. maxVelocity (float): Maximum velocity used for planning the motion. If not provided, setting in the vcJointDriver will be used. maxAcceleration (float): Maximum acceleration used for planning the motion. If not provided, setting in the vcJointDriver will be used. maxDeceleration (float): Maximum deceleration used for planning the motion. If not provided, setting in the vcJointDriver will be used. The value must be positive. maxJerk (float): Maximum jerk used for planning the motion. If not provided, setting in the vcJointDriver will be used. Returns: int: targetId assigned to the target. If the given targetId was positive, this will always be the same value. Exceptions: ValueError: When targetId is a negative value.
addIndependentTarget	Integer	Integer targetId, Integer driverIndex, Boolean isExternal, vcDriverTargetValueType valueType, Real value, Boolean isSynchronized, Optional Keyword[maxVelocity = Real], Optional Keyword[maxAcceleration = Real], Optional Keyword[maxDeceleration = Real], Optional Keyword[maxJerk = Real]	Call to add an independent motion target for a specific internal or external driver into an internal buffer. Call moveIndependent() to plan and clear all targets from this buffer. A target can have a target value for either position or velocity, selected with the valueType parameter. It is possible to synchronize the durations of motions resulting from selected targets. The value of "isSynchronized" will determine whether See more this target is included in the list of motions to synchronize - other motions will remain time optimal. The synchronization is only performed when planning the motions and is not updated subsequently if, e.g., a new un-synchronized target is given to one of the involved drivers before the motions have been completed. If target.TargetId is a positive integer, it is taken to mean an expected targetId value. This id value must not already be in use unless it was used for this same driver. If target.TargetId is zero, the next free id is automatically assigned to this target, and returned from this method call. An independent motion can replace a previous independent motion for the same driver. targetId does not have to be the same as that of the previous motion but it can be. The previous motion will be cancelled, i.e., TargetStatusChanged with 'Cancelled' eventType will be raised. Parameters: targetId (int): Identification number for the target. driverIndex (int): Index of the driver that this target applies to. isExternal (bool): False if this target applies to an internal driver, True if it applies to an external driver. valueType (vcDriverTargetValueType): Determines what the 'value' parameters means. value (float): The target value. Also see valueType. isSynchonized (bool): If True, this target will be marked to be synchronized with other targets for which this parameter is True. maxVelocity (float): Maximum velocity used for planning the motion. If not provided, setting in the vcJointDriver will be used. maxAcceleration (float): Maximum acceleration used for planning the motion. If not provided, setting in the vcJointDriver will be used. maxDeceleration (float): Maximum deceleration used for planning the motion. If not provided, setting in the vcJointDriver will be used. The value must be positive. maxJerk (float): Maximum jerk used for planning the motion. If not provided, setting in the vcJointDriver will be used. Returns: (int): targetId assigned to the target. If the given targetId was positive, this will always be the same value. Exceptions: ValueError: When targetId is a negative value.
checkDriverValueLimits	Boolean	None	Verifies that all vcJointDrivers in this vcMotionController fall within their current min and max hard limits. See more If this is true, or there are no such drivers, it returns true. Otherwise, returns false. Returns: bool: True if all drivers fall within their limits, False otherwise.
checkLimits	Boolean	List[Real] internalDriverValues, List[tuple[Integer, Real]] externalDriverValues	Verifies that all vcJointDrivers in this vcMotionController fall within their current min and max hard limits. See more If this is true, or there are no such drivers, it returns true. Otherwise, returns false. Parameters: internalDriversValues (list[float]): Values to check for internal drivers. externalDriversValues (list[(int, float]): Values to check for external drivers. Returns: bool: True if all drivers fall within their limits, False otherwise. Exceptions: ValueError: When internalDriverValues or externalDriverValues do not have exactly the same amount of values current found on the controller.
clearTargets	None	None	If there are any queued vcMotionControllerTargets, clears them for the queue.
createDriver	vcJointDriver	String name	Creates a new driver and adds it to this process controller's internal vcJointDrivers. See more Parameters: name (str): The process name has to be unique within this process executor's processes. Returns: vcJointDriver: The newly created driver. Exceptions: ValueError: When given name is empty.
createGroup	vcControllerGroup	Optional Keyword[name = String]	Creates a group into this controller, then returns a reference to the created group. See more The name is set if given, otherwise a free name will be assigned. Parameters: name (str): An optional name to set for the new group. Returns: vcControllerGroup: The created group.
deleteGroup	None	String groupName	Deletes the group from this controller. Also see vcControllerGroup.delete(). See more Parameters: groupName (str): The name of the group to delete. Exceptions: ValueError: When a group with the given name cannot be found.
getDriverPosition	Real	Integer index	Returns a specific internal driver's current position value. See more Parameters: index (int): The index used to get the driver. This must be less than DriverCount. Returns: float: The current position value of the driver. Exceptions: ValueError: When given index is out of bounds.
getDriversOutOfLimits	tuple[list[Integer], list[Integer]]	List[Real] internalDriverValues, List[tuple[Integer, Real]] externalDriverValues	Verifies that all vcJointDrivers in this vcMotionController fall within their current min and max hard limits. See more If this is true, or there are no such drivers, it returns true. Otherwise, returns false. Parameters: internalDriversValues (list[float]): Values to check for internal drivers. externalDriversValues (list[(int, float]): Values to check for external drivers. Returns: (list[int], list[int]): A tuple with separate lists for internal and external drivers that were found to be out of limits. Exceptions: ValueError: When internalDriverValues or externalDriverValues do not have exactly the same amount of values current found on the controller.
getNearestValues	list[Real]	List[Real] targetValues, List[Real] referenceValues, Boolean respectLimits	A helper method for adjusting full driver rotations so that the end results are as close to the given reference values as possible. See more This will only ever apply +/- 360 degrees steps, even if vcJointDriver.TurnSpan has another value. If vcJointDriver.TurnSpan is zero, this method has no effect on that driver. Parameters: targetValues (list[float]): The desired values in any revolution. For example, results of vcKisolver.inverse(). referenceValues (list[float]): Reference values guide turn selection. For example, last known internal driver values. respectLimits (bool): If True, solution outside driver limits are not accepted. Exceptions: RuntimeError: When respectLimits was true and the method couldn't converge on good values. Returns: list[float]: Nearest values.
moveCoordinated	Boolean	None	This method should be called after adding one or more coordinated targets (see addCoordinatedTarget). This will make sure that motion execution is See more ongoing and will trigger motion planning if the next coordinated target can be started immediately. If motion is already ongoing and cannot be interrupted at this time, planning the next motion will happen when the current motion finishes or enters its blending zone. This method is non-blocking. If you want to know when the motion completes, start awaiting for the OnTargetStatusChanged event before calling this method. Returns: bool: True on success, false on error.
moveIndependent	tuple[Integer, Integer]	None	This call plans and starts all independent motions added since the last call to this method. Also see addIndependentMotion. See more This method is non-blocking. If you want to know when the motion completes, start awaiting for the OnTargetStatusChanged event before calling this method. Return code values: -10: Unable to schedule next event -9: Overshoot detected -8: Cartesian profile in use -7: Profile synchronization failed -6: Profile calculation failed -5: Unable to get Cartesian data -4: Unable to get driver data -3: Unexpected target type -2: Driver not found -1: Driver in use (in coordinated motion) 0: No targets to plan Positive numbers: Count of planned targets Returns: tuple[int, int]: A tuple consisting of a return code and the targeId that failed in planning, or zero.
resume	None	None	Resumes motion if it was stopped. Parameters: None Returns: None
setDriverPosition	None	Integer index, Real value	Sets a specific internal driver's current position value. See more Parameters: index (int): The index used to get the driver. This must be less than DriverCount. value (float): The value to set to the driver. Exceptions: ValueError: When given index is out of bounds.
setToolCenterPoint	tuple[Boolean, list[vcJointDriver]]	vcMatrix newPosition, vcMotionCoordinateSystem coordinateSystem, Boolean pickNearestTurns, Boolean respectLimits, vcRobotConfiguration desiredConfiguration	An advanced setter for current tool center point position. See more Parameters: newPosition (vcMatrix): The position to set. coordinateSystem (vcMotionCoordinateSyetem): The coordinate system to use when setting the position. pickNearestTurns (bool): If True, turn handling is invoked. respectLimits (bool): If True, driver limits are respected. desiredConfiguration (vcMotionConfiguration): The desired configuration to attain when setting the position. Exceptions: RuntimeError: When respectLimits was true and the method couldn't converge on good values. Returns: (bool, list[vcJointDriver]): A boolean True if the position was reachable and a list of drivers that went out of limits, if any.
stop	Boolean	None	Stops all movement (immediate) without clearing the target / motion queue. See more Resume motion by calling resume(), moveIndependent() or moveCoordinated(). Parameters: None Returns: bool: True on success.
updateDriverLinks	None	None	Updates all vcNodes in the component that are affected by vcJointDrivers in this controller.
waitUntilTargetsReached	object	Optional[List[Integer] targetIds], Optional Keyword[timeout = Real]	Blocks script execution until given targets are reached. This function returns an awaitable task. It must be awaited. See more If no targetIds are specified, the awaitable is done when the next motion has fully completed, i.e., a target has been reached exactly. If one or more targetIds are specified, the awaitable is done when all of those motions have finished or failed, or have been cancelled. Parameters: targetIds list[int]: An optional list of target ids of the motions to monitor. timeout [float]: An optional time out value, in seconds. Returns: Awaitable[Tuple]: The task instance. When awaited returns a list of tuples, where the tuples are received OnStatusChanged event arguments, in the order they were raised in.

Events

Learn how to use events here. The events are also inherited from the parent class.

Name	Parameters	Description
OnGroupAdded	vcControllerGroup group	Triggered when a new controller group is created in this controller. Parameters: group (vcRobotics2.vcControllerGroup): new group.
OnGroupRemoved	None	Triggered when a controller group has been deleted from this controller.
OnPositionUpdated	vcMotionController controller	Triggered when controller updated the robot's state e.g. driver positions Parameters: controller (vcMotionController): Sender.
OnTargetStatusChanged	vcMotionController controller, vcTargetStatusChangedEventType eventType, int targetId	Triggered when a notable event happens in a programmed motion, e.g. the motion has been finished. See more Parameters: controller (vcMotionController): Sender. eventType (vcTargetStatusChangedEventType): Defines what kind of event happened. targetId (int): Matches the targetId value of the vcMotionTarget that was used to plan this motion.

Example: Robot Pose to Target

from vcCore import *
from vcFeatures import *
from vcGeometry import *
from vcBehaviors import *
from vcRobotics2 import *

def robot_pose_to_target(controller: vcMotionController, type: vcMotionTargetType, toolName="Null", baseName="Null") -> vcLinearTarget | vcPtpTarget | vcMultiDriverTarget:
  """Compile robot target from curen robot position, based on motion target type, tool and base data. (Excludes speed data)"""

  # Controller driver positions
  internalDriverPositions = controller.DriverPositions
  externalDriverPositions = controller.ExternalDriverPositions

  # Joint target does not require solving
  if type == vcMotionTargetType.MULTIDRIVER:
    target: vcMultiDriverTarget = controller.createTarget(type)
    target.InternalDriverValues = [(i, val) for i, val in enumerate(internalDriverPositions)]
    target.ExternalDriverValues = externalDriverPositions
    return target

  # Cartesian targets require use of kinematic solver
  if type == vcMotionTargetType.LINEAR or vcMotionTargetType.PTP:
    
    # Kinematics object for controller
    kinematics = controller.Kinematics

    # Create solver for calculating forward kinematic solution for pose
    solver = kinematics.createSolver()
    
    # Define all forvard solution related information
    solver.RootMatrix = controller.Component.WorldPositionMatrix
    solver.BaseMatrix = kinematics.findBase(baseName).PositionMatrix
    solver.ToolMatrix = kinematics.findTool(toolName).PositionMatrix
    
    # Fill in preoperties based on target type
    target: vcLinearTarget | vcPtpTarget = controller.createTarget(type)
    target.Target = solver.forward(internalDriverPositions)
    if isinstance(target, vcLinearTarget):
      target.InternalDriverValues = internalDriverPositions
    if isinstance(target, vcPtpTarget):
      target.DriverReferenceValues = internalDriverPositions
    target.ExternalDriverValues = externalDriverPositions
    
    return target
# Snippet ------------------------------------

def OnReset():
  controller: vcMotionController = getComponent().findBehaviorsByType(vcBehaviorType.ROBOTICS2_MOTIONCONTROLLER)[0]
  target = robotPoseToTarget(controller, vcMotionTargetType.LINEAR, "TOOL[1]", "BASE_2")

Example: Get Pose Configuration

from vcCore import *
from vcFeatures import *
from vcGeometry import *
from vcBehaviors import *

from vcRobotics2 import *


# Snippet ------------------------------------
def get_pose_configuration(controller: vcMotionController, target: vcLinearTarget | vcPtpTarget | vcMultiDriverTarget):
  """Gets the solved driverConfiguration information value for a target defined in cartesian format"""
  
  # create solver for calculating configuration based on driver values
  solver = controller.Kinematics.createSolver()
  
  # values for robots joints
  if isinstance(target, vcMultiDriverTarget):
    internalDriverValues = [val[1] for val in target.InternalDriverValues]
  if isinstance(target, vcLinearTarget):
    internalDriverValues = target.InternalDriverValues
  if isinstance(target, vcPtpTarget):
    internalDriverValues = target.DriverReferenceValues

  # Solve objects value and description. example: ('FRONT BELOW NOFLIP', 1)
  configurationObject = solver.getConfiguration(internalDriverValues)
  configEnumProperty: vcIntEnumProperty = configurationObject.Properties[0]
  description = configEnumProperty.ValueDescription
  value = configEnumProperty.Value
  
  return description, value
# Snippet ------------------------------------


def OnReset():
  controller: vcMotionController = getComponent().findBehaviorsByType(vcBehaviorType.ROBOTICS2_MOTIONCONTROLLER)[0]
  solver = controller.Kinematics.createSolver()  
  mat = solver.forward(controller.DriverPositions)
  target: vcLinearTarget = controller.createTarget(vcMotionTargetType.LINEAR)
  target.Target = mat
  target.InternalDriverValues = controller.DriverPositions
  print(target.Target)
  print(getPoseConfiguration(controller, target))